home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / windows / ll_110.zip / LOGLIST.DOC < prev    next >
Text File  |  1996-05-27  |  21KB  |  573 lines
  1.  
  2.                             TBBS Log-Lister
  3.  
  4.                              by Paul Blitz
  5.  
  6.                              Version 1.10
  7.                                20 May 96
  8.  
  9.  
  10. Introduction
  11. ============
  12.  
  13. Last year, I wrote some simple programs to list out certain (fixed) fields
  14. from the userlog to a text file. Michael Muller suggested that a more
  15. complete & more flexible program would be useful, especially so that the
  16. output files could be used with TYPE 1 & 2 text listing commands. Another
  17. sysop later pointed out that LogLister will also be suitable to produce
  18. simple lists to use with type 20 Keyword Searches.
  19.  
  20. Log-Lister allows you to create your own customised lists from your TBBS
  21. userlog file. These files list one user's details per line, and may include
  22. colourisation commands (using "%Xnn%" sequences), fixed text, headings,
  23. tabs, as well as the data itself.
  24.  
  25. The "definition" of the output is made in the configuration file: you can
  26. have several of these, and simply call up the one you want to use on the
  27. program's command line.
  28.  
  29. Log-Lister is a DOS program, and would typically be called as part of your
  30. night-time external event, from the relevant batch file (that's YOUR
  31. problem, not mine... <grin>)
  32.  
  33. This version of Log Lister has been written for use with TBBS 2.3.
  34.  
  35.  
  36. New in version 1.10
  37. ===================
  38.  
  39. It suddenly occurred to me that, in this world of the Internet, I ought to
  40. be supporting HTML somehow! The main thing that the program needed was the
  41. ability to ignore <things inside HTML "codes">.... which is what I've done.
  42. If you include the "X2" keyword, then anything within "<>" pairs is ignored
  43. (as far as delting excessive text) when tabs are done, just like %Xnn%
  44. sequences are ignored.
  45.  
  46.  
  47. Future Versions
  48. ===============
  49.  
  50. I hope that there will be enough interest to make it worthwhile improving
  51. the program further.... if you have any suggestions for improvements to
  52. the program, then let me know (see the end for contact addresses)
  53.  
  54. When you register, your "registration key" will be valid for all future
  55. "non-major" upgrades to the program.
  56.  
  57.  
  58. Running the program
  59. ===================
  60.  
  61. LOGLIST.EXE and your TBBS userlog (USERLOG.BBS) do *not* need to be
  62. together in the same directory, as long as you define a full path to your
  63. userlog. Unless Borland have screwed up the pascal compiler, your userlog
  64. is only ever opened for READING, so your userlog won't be disturbed in any
  65. way.
  66.  
  67. The program calling syntax is:
  68.  
  69.     LOGLIST <config file>
  70.  
  71. If you don't give a config file, then "LOGLIST.CFG", in the current
  72. directory, will be used.
  73.  
  74. The filename may include a full pathname, upto a maximum length of 50
  75. characters.
  76.  
  77. The config file not only contains formatting information, but gives the
  78. paths & filenames for the USERLOG.BBS file, the output text file, and the
  79. log file. This allows you to have multiple configuration files to produce
  80. several output files.
  81.  
  82.  
  83. The program will return one of several error levels when it exits:
  84.  
  85.     0 : Program ran OK
  86.     1 : Error in command line parameters
  87.     2 : Can't find file
  88.     3 : Error in config file
  89.     9 : Control-C / Escape was pressed during program
  90.     99: Internal processing error (eg: out of range value)
  91.  
  92. All errors will also return an error message on the screen (and the log
  93. file), with as much useful information as possible.
  94.  
  95. To help get you going, I've included some demo config files... if *you* do
  96. any good configs, please send them to me, and I'll include them (and then
  97. you could become famous!!)
  98.  
  99.  
  100. How it works
  101. ============
  102.  
  103. The program simply creates a textual list file, which can either be
  104. printed, or can be viewed online by your callers (eg with a TYPE1). The
  105. file contains page headers, and one line of text for each user in your
  106. userlog..... or rather for each user who matches the "restriction criteria"
  107. (see below).
  108.  
  109. You can define a "page length": when you do this, the program will insert a
  110. "%MORE%" at the relevant places. When viewed online, the user will then see
  111. the data a page at a time.
  112.  
  113. The file can have a set of file- and page-header lines, and a set of
  114. page-bottom lines: these are copied from the config file verbatim, so may
  115. contain "real-time" substitution parameters which TBBS will expand for you.
  116.  
  117. The lines of user data are then built up from lines of different types of
  118. data (eg words, substitution parameters and colourisation commands). If the
  119. data contains substitution parameters, then they are replaced by the
  120. relevant data from the userlog records.
  121.  
  122. For example, the set of data might include:
  123.  
  124.   header "A list of names etc"
  125.   header "-------------------"
  126.   %X03%
  127.   %NAME%
  128.   Tab to column 20
  129.   %X95%
  130.   %PHONE%
  131.   Tab to column 35
  132.   %X22%
  133.   %ADDR1%
  134.   a ","
  135.   a space
  136.   %ADDR2%
  137.   a "."
  138.  
  139. (this is NOT actually how the data is defined... see below)
  140.  
  141. This would give a list something like this:
  142.  
  143. A list of names etc
  144. -------------------
  145. Paul Blitz         %X95%441962885696   %X22%25 Woodgreen Road, Winchester.
  146. Phil Becker        %X95%303 699 6565   %X22%15200 E. Girard Ave., Aurora.
  147. .... etc
  148.  
  149. The "file header" gets printed once, at the top of the file. The "page
  150. headers" are printed at the top of the second and subsequent pages (after a
  151. "%MORE%").
  152.  
  153. The way the data is created is defined by the config file (see below). If
  154. you want to create several lists, then you simply create multiple
  155. configuration files, and run LOGLIST multiple times, specifying the
  156. different config files.
  157.  
  158.  
  159.  
  160. Config File format
  161. ==================
  162.  
  163. The config file format is, I hope, fairly straight-forward, and if best
  164. understood by looking at the supplied demo config files.
  165.  
  166. Column 1 of the file defines what that line is:
  167.  
  168.   U or u  - path & filename of your USERLOG.BBS file
  169.   O or o  - path & filename of the output file
  170.   L or l  - path & filename of the log file
  171.   F or f  - a file header line
  172.   P or p  - a page header line
  173.   B or b  - a page bottom line
  174.   R or r  - restriction criteria
  175.   D or d  - a data field
  176.   S or s  - a space setting
  177.   T or t  - a tab setting
  178.   M or m  - lines after which to insert a "%MORE%"
  179.   X or x  - special options
  180.  
  181. Anything else in column 1 will cause the rest of the line to be ignored:
  182. this is a good way of adding comments. To cover future expansion, I'd
  183. advise using a ";", as that will be reserved for comments in all future
  184. versions for comment lines (anything else could get used for something!)
  185.  
  186. Column 2 onwards holds the data. The line of data is ended by a <cr>
  187. (chr(13)). To make things predictable, all TRAILING spaces are removed (use
  188. the "S" or "T" command to include spaces at the end of the data)
  189.  
  190. Apart from the headers and comments, you may have upto 200 "items". These
  191. will display in the order they appear in the config file.
  192.  
  193.  
  194. Userlog, Output and Log files:
  195. ------------------------------
  196. These three line types define where your userlog, output, and error log
  197. files are. If you are silly enough to duplicate either of these, then the
  198. last one will be used. Each path/filename may be upto 50 characters long.
  199.  
  200. If the userlog file can not be found, the program will abort.
  201.  
  202. The output file will simply overwrite any existing file.
  203.  
  204. The log file will simply append to any existing file: at a minimum, the log
  205. will list the date / time of the run, and the config files used. The log
  206. file is not opened until the config file has been read (as that is where
  207. the error log's name is defined), so errors in the config file which cause
  208. a program abort will not be logged (if this becomes a big problem, let me
  209. know, and I'll work out a way around it).
  210.  
  211. You would normally put these as the first three lines of your config file.
  212.  
  213.  
  214. File Header lines:
  215. ------------------
  216. You can have up to 10 file header lines, each limited to being 120
  217. characters long. They are simply copied verbatim to the beginning of the
  218. output file in the order they appear in the config file.
  219.  
  220. Whilst they need not be in a block at the top of the file, you'll probably
  221. find it easier if they are!
  222.  
  223. You can include ANY substit